home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 January / macformat-020.iso / Shareware City / Developers / apps.to.go / DTS.Lib / =Using TextEditControl.c < prev    next >
Encoding:
Text File  |  1994-05-04  |  7.8 KB  |  174 lines  |  [TEXT/MPS ]
  1. ***** TextEditControl.c usage documentation *****/
  2.  
  3. Purpose:  To simplify TextEdit handling within a window.
  4.  
  5. Implementing a TextEdit control does the following:
  6.  
  7. 1) Makes using TextEdit in a non-dialog window easy.
  8. 2) The TERecord is automatically associated with the window, since
  9.    it is in the window's control list.
  10. 3) The TextEdit control can have scrollbars associated with it, and these
  11.    are also kept in the window's control list, and also associated with
  12.    the TextEdit control.
  13. 4) Updating of the TERecord is much simpler, since all that is
  14.    necessary is to draw the control (or all the window's controls with
  15.    a DrawControls call).
  16. 5) What isn't handled automatically by tracking the control can be handled
  17.    with a direct call.  There are simple calls to handle TextEdit events.
  18. 6) Undo is already supported.
  19. 7) A TERecord length can be specified.  This length will not be exceeded
  20.    when editing the TERecord.
  21. 8) When you close the window, the TERecord is disposed of.
  22.    (This automatic disposal can easily be defeated.)
  23.  
  24.  
  25. To create a TextEdit control, you only need a single call.  For example:
  26.  
  27.     mode = cteVScrollLessGrow;    /* TERecord read-write, with vertical scroll         */
  28.                                 /* that leaves space for grow box.                     */
  29.  
  30.     CTENew(rViewCtl,            /* Resource ID of view control for TextEdit control. */
  31.            window,                /* Window to hold TERecord.                             */
  32.            true,                /* Initially visible.                                 */
  33.            &teHndl,                /* Return handle for TERecord.                         */
  34.            &ctlRect,            /* Rect for TextEdit view control.                     */
  35.            &destRect,            /* destRect for TERecord                             */
  36.            &viewRect,            /* viewRect for TERecord                             */
  37.            &brdrRect,            /* Used to frame a border.                             */
  38.            32000,                /* Max size for TERecord text.                         */
  39.            mode);
  40.  
  41. The various choices for the TextEdit control are defined as follows:
  42.  
  43. #define cteReadOnly            0x0001
  44. #define cteHScroll            0x0002
  45. #define cteHScrollLessGrow    0x0006
  46. #define cteVScroll            0x0008
  47. #define cteVScrollLessGrow    0x0018
  48. #define cteActive            0x0020
  49. #define cteNoBorder            0x0040
  50. #define cteShowActive        0x0080
  51. #define cteTabSelectAll        0x0100
  52. #define cteTwoStep            0x0200
  53. #define cteScrollFullLines    0x0400
  54. #define cteStyledTE            0x0800
  55. #define cteCenterJustify    0x1000
  56. #define cteRightJustify        0x2000
  57. #define cteNoFastKeys        0x4000
  58.  
  59. cteReadOnly:        Don't allow editing.  When selected, don't blink a caret.
  60.                     Allow text selection and copy-to-clipboard.
  61. cteHScroll:            Create and manage a horizontal scrollbar for the TextEdit control.
  62. cteHScrollLessGrow:    Create and manage a horizontal scrollbar for the TextEdit control,
  63.                     but leave space for a growIcon on the right end of the scrollbar.
  64. cteVScroll:            Create and manage a vertical scrollbar for the TextEdit control.
  65. cteVScrollLessGrow:    Create and manage a vertical scrollbar for the TextEdit control,
  66.                     but leave space for a growIcon on the bottom end of the scrollbar.
  67. cteActive:            Make this the initially active control for the window.
  68. cteNoBorder:        By default, you get a border around the TextEdit control.  To turn this
  69.                     off, set this bit.
  70. cteShowActive:        When the control is active, show that it is by drawing a selection
  71.                     border around the control.  This is the new 7.0 human-interface
  72.                     method of showing which control is active.  (This can be an important
  73.                     indicator because if you have readOnly TextEdit controls, they don't
  74.                     have a blinking caret.  If they also don't have any text selected,
  75.                     there will be no indication that it is the active control.
  76. cteTabSelectAll:    When using IsCtlEvent() (discussed under "! using CtlHandler.c"),
  77.                     tab changes the active TextEdit (or List) control.  When a TextEdit
  78.                     control is made active, sometimes it is desirable to initially select
  79.                     all of the text for the user.  Setting this bit accomplishes this.
  80. cteTwoStep:            When using IsCtlEvent(), you may want the initial click on a TextEdit
  81.                     control to just select the control, or you may wish the click to start
  82.                     tracking in addition to selecting the control.  The tracking is
  83.                     considered the second step, so by setting this bit, you will get
  84.                     tracking of the control on the initial click.
  85. cteScrollFullLines:    This does as it sounds, but only if the TextEdit control isn't styled.
  86. cteStyledTE:        If you don't need styles for this TextEdit control, leave this bit off.
  87. cteCenterJustify:    As it sounds.
  88. cteRightJustify:    As it sounds.
  89. cteNoFastKeys:        The fast-keys feature allows the TextEdit control to check the OSEvent queue
  90.                     to see if there is another key event.  If there is, it will handle it
  91.                     before returning control to the application.  This local event processing
  92.                     allows a great speed increase in TextEdit performance, especially on
  93.                     slower Macs.  Some applications will want to inhibit this behavior.  Set
  94.                     this bit if you do.
  95.  
  96. Simply initialize ctlRect, destRect, viewRect, and brdrRect appropriately, and
  97. then call CTENew (which stands for Control TENew).  If teHndl is returned
  98. nil, then CTENew failed.  Otherwise, you now have a TextEdit control in the
  99. window.  If it fails, it also returns an error stating why it failed
  100. (memFullErr or resNotFound).
  101.  
  102. NOTE: There is a TextEdit bug (no way!!) such that you may need to set the
  103.       viewRect right edge 2 bigger than the right edge of destRect.  If you
  104.       do not do this, then there will be some clipping on the right edge in
  105.       some cases.  Of course, you may want this.  You may want horizontal
  106.       scrolling, and therefore you would want the destRect substantially
  107.       larger than the viewRect.  If you don't want horizontal scrolling,
  108.       then you probably don't want any clipping horizontally, and therefore
  109.       you will need to set destRect.right 2 less than viewRect.right.
  110.  
  111.  
  112. If the CTENew call succeeds, you then have a TextEdit control in your
  113. window.  It will be automatically disposed of when you close the window.
  114. If you don't waht this to happen, then you can detach it from the
  115. view control which owns it.  To do this, you would to the following:
  116.  
  117.     viewCtl = CTEViewFromTE(theTextEditHndl);
  118.     if (viewCtl) SetCRefCon(viewCtl, nil);
  119.  
  120. The view control keeps a reference to the TERecord in the refCon.
  121. If the refCon is cleared, then the view control does nothing.  So, all that
  122. is needed to detach a TERecord from a view control is to set the
  123. view control's refCon nil.  Now if you close the window, you will still
  124. have the TERecord.
  125.  
  126.  
  127. To remove a TextEdit control completely from a window, you make one call:
  128.  
  129.     CTEDispose(theTextEditHndl);
  130.  
  131. This disposes of the TERecord, the view control, and any scrollbar
  132. controls that were created when the TextEdit control was created with
  133. the call CTENew.
  134.  
  135.  
  136. Events for TERecord are handled nearly automatically.  You can
  137. make one of 3 calls:
  138.  
  139.     CTEClick(window, eventPtr, &action);
  140.     CTEEvent(window, eventPtr, &action);
  141.     CTEKey(window, eventPtr);
  142.  
  143. In each case, if the event was handled, non-zero is returned.  CTEEvent simply
  144. calls either CTEClick or CTEKey, whichever is appropriate.
  145.  
  146. Another call you will want to use is CTEEditMenu.  This is used to set the
  147. state of cut/copy/paste/clear for TextEdit controls.  It checks the active
  148. control to see if text is selected, if the control is read-only, etc.
  149. Based on this information, it sets cut/copy/paste/clear either active
  150. or inactive.  If any menu items are set active, it returns true.
  151.  
  152.  
  153. One more high-level call is CTEUndo().  In response to an undo menu item
  154. being selected by the user, just call CTEUndo(), and the edits the user
  155. has made will be undone.  (This includes undoing an undo.)
  156.  
  157.  
  158. The last high-level call for managing the edit menu is CTEClipboard.  Call it
  159. when you want to do a cut/copy/paste/clear for the active TextEdit control.
  160. The value to pass is as follows:
  161.  
  162.  2: cut
  163.  3: copy
  164.  4: paste
  165.  5: clear
  166.  
  167. These are the same values you would pass to a DA for these actions.
  168.  
  169.  
  170.  
  171. For a complete list of the TextEdit control functions and a description as to
  172. their purpose, see the file TextEditControl.h.
  173.  
  174.